Connection Factories

There are two kinds of basic JMS connection-factory:

• In-VM connection factories can be used by a local client (i.e. one running in the same JVM as the server)

• Netty connections factories can be used by a remote client. 

There is also a pooled-connection-factory which is special in that it leverages the outbound adapter of the HornetQ JCA Resource Adapter.  It is also special because:

• It is only available to local clients, although it can be configured to point to a remote server.

• As the name suggests, it is pooled and therefore provides superior performance to the clients which are able to use it.  The pool size can be configured via the max-pool-size and min-pool-size attributes.

• It should only be used to send (i.e. produce) messages.

• It can be configured to use specific security credentials via the user and password attributes.  This is useful if the remote server to which it is pointing is secured.

To be clear, the inbound adapter of the HornetQ JCA RA (which is for consuming messages) is only used by MDBs and is not available to other kinds of clients.

Both a connection-factory a pooled-connection-factory reference a connector declaration.  

A netty-connector is associated with a socket-binding which tells the client using the connection-factory where to connect.

• A connection-factory referencing a netty-connector is suitable to be used by a remote client to send messages to or receive messages from the server (assuming the connection-factory has an appropriately exported entry).  

• A pooled-connection-factory referencing a netty-connector is suitable to be used by a local client to send messages to a remote server granted the socket-binding references an outbound-socket-binding pointing to the remote server in question.

An in-vm-connector is associated with a server-id which tells the client using the connection-factory where to connect (since multiple HornetQ servers can run in a single JVM).

• A connection-factory referencing an in-vm-connector is suitable to be used by a local client to either send messages to or receive messages from a local server.  

• A pooled-connection-factory referencing an in-vm-connector is suitable to be used by a local client only to send messages to a local server.

The entry declaration of a connection-factory or a pooled-connection-factory specifies the JNDI name under which the factory will be exposed.  Only JNDI names bound in the "java:jboss/exported" namespace are available to remote clients.  If a connection-factory has an entry bound in the "java:jboss/exported" namespace a remote client would look-up the connection-factory using the text after "java:jboss/exported".  For example, the "RemoteConnectionFactory" is bound by default to "java:jboss/exported/jms/RemoteConnectionFactory" which means a remote client would look-up this connection-factory using "jms/RemoteConnectionFactory".  A pooled-connection-factory should not have any entry bound in the "java:jboss/exported" namespace because a pooled-connection-factory is not suitable for remote clients.

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <connectors>
      <netty-connector name="netty" socket-binding="messaging"/>
      <netty-connector name="netty-throughput" socket-binding="messaging-throughput">
          <param key="batch-delay" value="50"/>
      </netty-connector>
      <in-vm-connector name="in-vm" server-id="0"/>
   </connectors>
   [...]
   <jms-connection-factories>
      <connection-factory name="InVmConnectionFactory">
          <connectors>
              <connector-ref connector-name="in-vm"/>
          </connectors>
          <entries>
              <entry name="java:/ConnectionFactory"/>
          </entries>
      </connection-factory>
      <connection-factory name="RemoteConnectionFactory">
          <connectors>
              <connector-ref connector-name="netty"/>
          </connectors>
          <entries>
              <entry name="RemoteConnectionFactory"/>
              <entry name="java:jboss/exported/jms/RemoteConnectionFactory"/>
          </entries>
      </connection-factory>
      <pooled-connection-factory name="hornetq-ra">
          <transaction mode="xa"/>
          <connectors>
              <connector-ref connector-name="in-vm"/>
          </connectors>
          <entries>
              <entry name="java:/JmsXA"/>
          </entries>
      </pooled-connection-factory>
   </jms-connection-factories>
   [...]
</subsystem>

_{(See standalone/configuration/standalone-full.xml)}

JMS Queues and Topics

JMS queues and topics are sub resources of the messaging subsystem.  They are defined in the jms-destinations section.  One can define either a jms-queue or jms-topic.  Each destination must be given a name and contain at least one entry element.

Each entry refers to a JNDI name of the queue or topic.  Keep in mind that any jms-queue or jms-topic which needs to be accessed by a remote client needs to have an entry in the "java:jboss/exported" namespace.  As with connection factories, if a jms-queue or jms-topic has an entry bound in the "java:jboss/exported" namespace a remote client would look it up using the text after "java:jboss/exported".  For example, the following jms-queue "testQueue" is bound to "java:jboss/exported/jms/queue/test" which means a remote client would look-up this jms-queue using "jms/queue/test".  A local client could look it up using "java:jboss/exported/jms/queue/test", "java:jms/queue/test", or more simply "jms/queue/test":

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <jms-destinations>
       <jms-queue name="testQueue">
           <entry name="jms/queue/test"/>
           <entry name="java:jboss/exported/jms/queue/test"/>
       </jms-queue>
       <jms-topic name="testTopic">
           <entry name="jms/topic/test"/>
           <entry name="java:jboss/exported/jms/topic/test"/>
       </jms-topic>
   </jms-destinations>
</subsystem>

_{(See standalone/configuration/standalone-full.xml)}

JMS endpoints can easily be created through the CLI:

[standalone@localhost:9999 /] jms-queue add --name=myQueue --entries=queues/myQueue

[standalone@localhost:9999 /] /subsystem=messaging/jms-queue=myQueue:read-resource
{
   "outcome" => "success",
   "result" => {"entries" => ["queues/myQueue"]},
   "compensating-operation" => undefined
}

A number of additional commands to maintain the JMS subsystem are available as well:

[standalone@localhost:9999 /] jms-queue --help --commands
add...removeTo read the description of a specific command execute'jms-queue command_name --help'.

Dead Letter & Redelivery

Some of the settings are applied against an address wild card instead of a specific messaging destination. The dead letter queue and redelivery settings belong into this group:

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <address-settings>
      <address-setting match="#">
         <dead-letter-address>jms.queue.DLQ</dead-letter-address>
         <expiry-address>jms.queue.ExpiryQueue</expiry-address>
         <redelivery-delay>0</redelivery-delay>
         [...]
      </address-setting>
   </address-settings>
   [...]
</subsystem>

_{(See standalone/configuration/standalone-full.xml)}

Security Settings for HornetQ addresses and JMS destinations

Security constraints are matched against an address wildcard, similar to the DLQ and redelivery settings.  Note: Multiple roles are separated by spaces.

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <security-settings>
      <security-setting match="#">
         <permission type="send" roles="guest"/>
         <permission type="consume" roles="guest"/>
         <permission type="createNonDurableQueue" roles="role1"/>
         <permission type="deleteNonDurableQueue" roles="role1 role2"/>
      </security-setting>
   </security-settings>
   [...]
</subsystem>

_{(See standalone/configuration/standalone-full.xml)}

Security Domain for Users

By default, HornetQ will use the "other" JAAS security domain.  This domain is used to authenticate users making connections to HornetQ and then they are authorized to perform specific functions based on their role(s) and the security-settings described above.  This domain can be changed by using security-domain, e.g.:

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <security-domain>mySecurityDomain</security-domain>
   [...]
</subsystem>

Deployment of -jms.xml files

Starting with JBoss Application Server 7.1.0.Final you have the ability to deploy a -jms.xml file defining JMS destinations, e.g.:

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
   <hornetq-server>
      <jms-destinations>
         <jms-queue name="sample">
            <entry name="jms/queue/sample"/>
            <entry name="java:jboss/exported/jms/queue/sample"/>
         </jms-queue>
      </jms-destinations>
   </hornetq-server>
</messaging-deployment>

Component Reference

The messaging subsystem is provided by the HornetQ project. Fo a detailed description of the available configuration properties, please consult the project documentation.